This could be reworded rather than removed, perhaps mentioning that only the failures in the block cause the behaviour?

The reason I've removed this was that If you want to declare an example pendingand bypass thebefore hooks as well was misleading. Replaced it with pending example method docs.

Actually this note needs to be here, as this is the doc for the pending example method? It is relevant to explain that before hooks are not skipped, so the alternative is the pending metadata.

Sorry, I don't understand what needs to remain.
As far as I understand, hooks aren't skipped in either case. In this regards, there is no alternative.
And all of:

pending 'example method' do
  # something that fails
end
it 'has a cool feature', pending: 'yet to be implemented' do # or just pending: true
  # cool missing feature test
end
it 'should work' do
  pending 'but does not'
  # and a failing expectation
end

are just different notations of the same example group that will pass if its expectations fail.

Am I missing something? I'm all for clarifying/extending the docs, but at this point I'm out of ideas on how to do this exactly.

This doc is explaining this difference:

RSpec.describe do
  before do
    raise "BOOM!"
  end

  it "will pend", pending: "Oh yes" do
    raise "Yeah nah"
  end

  it "will fail" do
    pending do
      raise "Won't happen"
    end
  end
end

*F

Pending: (Failures listed here are expected and do not affect your suite's status)

  1) will pend
     # Oh yes
     Failure/Error: raise "BOOM!"

     RuntimeError:
       BOOM!
     # ./spec/pending_example_spec.rb:3:in `block (2 levels) in <top (required)>'

Failures:

  1) will fail
     Failure/Error: raise "BOOM!"

     RuntimeError:
       BOOM!
     # ./spec/pending_example_spec.rb:3:in `block (2 levels) in <top (required)>'

Finished in 0.00349 seconds (files took 0.13413 seconds to load)
2 examples, 1 failure, 1 pending

Failed examples:

rspec ./spec/pending_example_spec.rb:10 # will fail

The difference being that pending metadata will cause a hook failure to be considered as part of the pending nature of the spec, where as the block will cause a failure as it hasn't reached the bit that can be pending.

Got it, thanks for the clarification!
Let me quickly get this note back.

Done.
I've extended the previous docs based on the assumption that if it wasn't clear at all for me, it wasn't clear for the majority.

I can extract those docs changes into separate PR, one for 4-0-dev, and another for main if you like.
Surely it doesn't relate to "Remove deprecations" much, especially in the part of pending.rb where only the error message was reduced not to mention RSpec 2.

#2872 #2873

I'm not sure if it's the best place for this doc.
Putting it to

This whole doc is about pending examples, if you'd like to change it can we do so in another PR with a diff of the rendered docs?

A summary of what is done here:

1. Replaced a confusing "an example" docstring of a describe statement:

- describe "an example" do
+ describe "some behaviour" do

2. Removed the misleading notion of a possibility to bypass hooks for any notation of a pending example:

- #`before(:example)` hooks are eval'd when you use the `pending`
- #   method within an example. If you want to declare an example `pending`
- #   and bypass the `before` hooks as well,

just because hooks are run either way.

3. Wrapped the example of pending example group alias into describe to make a distinction between pending example alias and pending example-scope method:

it "is pending with no message" do
  pending
end

vs

describe "an example" do
  pending "does not implement something yet" do
    # ...
  end
end

I admit I've repeated the mistake with "an example" docstring I've fixed in 1) 😆
Let me fix this real quick.

There is no massive change here, but surely it's hard to grasp what was made just by looking at the diff.

Actually this note needs to be here, as this is the doc for the pending example method? It is relevant to explain that before hooks are not skipped, so the alternative is the pending metadata.